Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(1624): first draft, prototype of context map grammar and diagram #5353

Draft
wants to merge 2 commits into
base: develop
Choose a base branch
from

Conversation

AngeloChecked
Copy link

@AngeloChecked AngeloChecked commented Mar 2, 2024

📑 Summary

Hi Mermaid Guys, this PR addresses the diagram discussed in this GitHub issue: 1624.

You can find a demo here: https://angelochecked.github.io/mermaid/

I've started implementing something, but it's in its early and raw stages. If anyone has a better prototype, please reach out to me (writing here) so I can contribute to it.

I've opened this draft pull request primarily to gather feedback from those more skilled than me in drawing 2D elements. I'll be working on this in my spare time, and I'm unsure when it will reach production grade. However, I'm very open to suggestions. If anyone wants to collaborate on the implementation of this diagram, please let me know.

I'm experimenting with rendering using plain d3 in this orphan branch: contextMapDiagramGluedPrototype branch.

Mermaid Devs: I hope this draft PR doesn't create noise. If it does, I can close it and use the related issues to seek feedback.
Additionally, feel free to share/post here any insights you believe could enhance both this contribution and the diagram implementation. Your input is greatly appreciated in beautifying and refining the the diagram implementation :).

I'll continue to provide updates here on the current state of the implementation.

Resolves #1624

📏 Design Decisions

I'm starting to experiment with the prototype design of this diagram using plain d3 in the simplest way possible. My decisions might be subjective, as I'm not particularly skilled in this domain of drawing d3 elements, but I'm learning along the way. I'm completely open to suggestions and improvements in the approach.

📋 Tasks

TODO:

Big Picture

  • 💻 have added necessary unit/e2e tests.
  • 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
  • styles and theme implementation
  • other? open to suggestions

Parsing

  • Basic recognition of the contextMap scope
  • Simple parsing of nodes using the contains prefix keywords
  • Simple parsing of links
  • Parsing of nodes with multiline contains keyword
  • additional features...? (teams...) open to suggestions

Diagram Rendering

  • Basic arrangement of nodes, labels, and links
  • Drawing simple nodes as ellipses
  • Drawing simple links
  • Drawing simple labels
  • Resolving label collisions
  • Resolving mid-link text collisions
  • Preventing link intersection with nodes
  • other? open to suggestions

@github-actions github-actions bot added the Type: Enhancement New feature or request label Mar 2, 2024
Copy link

netlify bot commented Mar 2, 2024

Deploy Preview for mermaid-js ready!

Name Link
🔨 Latest commit cae456f
🔍 Latest deploy log https://app.netlify.com/sites/mermaid-js/deploys/669bc91761a00b0008ac646d
😎 Deploy Preview https://deploy-preview-5353--mermaid-js.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@AngeloChecked
Copy link
Author

AngeloChecked commented Mar 2, 2024

As mentioned in the todo, my current focus is on addressing some key pain points:

  • Resolving label collisions
  • Resolving mid-link text collisions
  • Preventing link intersection with nodes

These issues are readily apparent in the demo

I'm completely open to suggestions and advice for enhancing the graph implementation. Please feel free to share here any thoughts or ideas you have in mind!

@AngeloChecked AngeloChecked marked this pull request as draft March 2, 2024 19:28
Copy link

codecov bot commented Mar 2, 2024

Codecov Report

Attention: Patch coverage is 0.60753% with 818 lines in your changes missing coverage. Please review.

Project coverage is 5.75%. Comparing base (3c3d28d) to head (cae456f).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           develop   #5353      +/-   ##
==========================================
- Coverage     5.85%   5.75%   -0.11%     
==========================================
  Files          274     283       +9     
  Lines        41112   41922     +810     
  Branches       488     522      +34     
==========================================
+ Hits          2408    2413       +5     
- Misses       38704   39509     +805     
Flag Coverage Δ
unit 5.75% <0.60%> (-0.11%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Coverage Δ
packages/mermaid/src/defaultConfig.ts 47.33% <100.00%> (+0.95%) ⬆️
.build/jsonSchema.ts 0.00% <0.00%> (ø)
packages/parser/src/language/contextMap/index.ts 0.00% <0.00%> (ø)
...s/mermaid/src/diagram-api/diagram-orchestration.ts 0.00% <0.00%> (ø)
packages/parser/src/language/index.ts 0.00% <0.00%> (ø)
...ges/parser/src/language/contextMap/tokenBuilder.ts 0.00% <0.00%> (ø)
packages/parser/src/parse.ts 0.00% <0.00%> (ø)
...maid/src/diagrams/context-map/contextMapDiagram.ts 0.00% <0.00%> (ø)
...aid/src/diagrams/context-map/contextMapDetector.ts 0.00% <0.00%> (ø)
...s/mermaid/src/diagrams/context-map/contextMapDb.ts 0.00% <0.00%> (ø)
... and 5 more

... and 1 file with indirect coverage changes

@AngeloChecked AngeloChecked force-pushed the feature/1624_Context-Map-Diagram-Prototype branch 2 times, most recently from e002223 to e5e3415 Compare March 3, 2024 01:03
@sidharthv96
Copy link
Member

Can you please refer to these PRs and use langium instead of jison?
We are migrating away from JISON, and would prefer new diagrams in langium, so that we don't have to do a migration.

@AngeloChecked
Copy link
Author

AngeloChecked commented Mar 3, 2024

Can you please refer to these PRs and use langium instead of jison? We are migrating away from JISON, and would prefer new diagrams in langium, so that we don't have to do a migration.

Hi! @sidharthv96, thanks a lot for the heads up! I totally missed that earlier.
I'm getting ideas from these PRs now! But I'm worried I might have missed some docs. Did I overlook something? Also, quick question: Should I stick with the 'packages/Mermaid' package or create a new one? Appreciate your help! 🙏

edit: is it acceptable for me to target the 'next' branch at this point?

@nirname nirname requested review from nirname and sidharthv96 March 3, 2024 18:53
@Yokozuna59
Copy link
Member

But I'm worried I might have missed some docs. Did I overlook something?

Currently, the documentation is kind of outdated, so it may not be relevant in some aspects, especially when creating new diagrams with Langium.

Also, quick question: Should I stick with the 'packages/Mermaid' package or create a new one? Appreciate your help! 🙏

You don't need to create a new package; just create new folders with the name of the diagram in:

  • packages/parser/src/language
  • packages/mermaid/src/diagrams

Then please refer to the listed PRs above to know what other files should be modified or added.

edit: is it acceptable for me to target the 'next' branch at this point?

Yes, the packages/parser exists only on the next branch for now. So it would be better if you checkouted from it instead of develop. It's fine if you targeted next now, but you may need to resolve conflict to update the current branch.

@Yokozuna59 Yokozuna59 self-requested a review March 5, 2024 18:40
@AngeloChecked
Copy link
Author

Hi @nirname

Thank you for the feedback! I'll update the naming convention.

Regarding Jison, I'm currently working on the ContextMap Langium parser here, so the Jison version will be changed.

PS: yep, I initially called it 'mini-context-map' because it might not fully implement the language reference. However, I later removed the prefix as it didn't seem relevant.

@benr77
Copy link

benr77 commented Jul 16, 2024

We are really interested in this feature. Has there been any progress recently? Happy to help test or otherwise assist. Thanks.

@AngeloChecked
Copy link
Author

We are really interested in this feature. Has there been any progress recently? Happy to help test or otherwise assist. Thanks.

Hi @benr77, sure!

I'm currently finishing the integration of the previous work with the new Langium parser. In a few days, I'll update this pull request with the master branch and resume work on the drawing part, which still lacks many features.

If you'd like, we can have a discussion on the Mermaid Discord once I wrap up my current task. Since I'm working on this in my spare time, my schedule isn't precise. I'm not an expert in this domain, so any insights or experience you can share would be super valuable. I'm also the first interested in making this kind of chart available on Mermaid, but consider that I'm treating it as an ongoing side project.

@benr77
Copy link

benr77 commented Jul 18, 2024

Hey @AngeloChecked thanks for the update. I am happy hear that this is still moving forward, and I completely understand it's a voluntary side project (I have several myself!).

Ping me a message when things are at a good stage to test, and I'll spend some time working with it and happy to report back with issues. I am no expert at context mapping or Mermaid but I am involved in a project whereby we are going to need this kind of diagramming a lot over the coming months so I'll have plenty of opportunities to test it.

Thanks!

@AngeloChecked AngeloChecked force-pushed the feature/1624_Context-Map-Diagram-Prototype branch from e5e3415 to 6cfcda8 Compare July 20, 2024 10:03
Copy link

argos-ci bot commented Jul 20, 2024

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build Status Details Updated (UTC)
default (Inspect) ✅ No changes detected - Jul 20, 2024, 2:37 PM

@AngeloChecked AngeloChecked force-pushed the feature/1624_Context-Map-Diagram-Prototype branch from 6cfcda8 to 8d3f4ac Compare July 20, 2024 10:17
@AngeloChecked AngeloChecked force-pushed the feature/1624_Context-Map-Diagram-Prototype branch from 8d3f4ac to 8613b08 Compare July 20, 2024 14:24
@AngeloChecked
Copy link
Author

Hi @nirname, @sidharthv96, @Yokozuna59

I've force-pushed the entire branch with the new Langium parser implementation (and solved some linting).

I'm very open to any feedback, corrections, or improvements (config, naming, testing...).

Now, I'm shifting my focus back to the drawing part.

@hemalvarambhia
Copy link

How can I start to use this feature on the live mermaid site?

@AngeloChecked
Copy link
Author

How can I start to use this feature on the live mermaid site?

Hi @hemalvarambhia, I’m focusing on other stuff right now, so progress on this is slowing down. I plan to return on this in a few days. It’s far from ready... I’m dealing with issues like overlapping elements and experimenting with the spring embedder-like solutions. I don’t have a timeline yet for a usable version on the Mermaid website, but knowing there’s interest motivates me to prioritize it when I’m back. Thanks!

@hemalvarambhia
Copy link

hemalvarambhia commented Nov 24, 2024

Hi @hemalvarambhia, I’m focusing on other stuff right now, so progress on this is slowing down. I plan to return on this in a few days. It’s far from ready... I’m dealing with issues like overlapping elements and experimenting with the spring embedder-like solutions. I don’t have a timeline yet for a usable version on the Mermaid website, but knowing there’s interest motivates me to prioritize it when I’m back. Thanks!

@AngeloChecked that's perfect. I'll try to keep an eye. I love drawing context maps as they've been helpful.

@AngeloChecked
Copy link
Author

@hemalvarambhia Let me refocus on this project, and if you'd like, we can set up an online meeting.

@hemalvarambhia
Copy link

@hemalvarambhia Let me refocus on this project, and if you'd like, we can set up an online meeting.

@AngeloChecked I'd love it if you could refocus. I am drawing a context map at the moment. Being able to draw one would provide developers with important information for their work.

@hemalvarambhia
Copy link

if you'd like, we can set up an online meeting.

@AngeloChecked I am happy to have that conversation ❤️. Can Zoom work?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Type: Enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Support for Domain Driven Design diagrams and syntax
6 participants